﻿<?xml version="1.0" encoding="utf-8" ?>
<SourceAnalyzer Name="Documentation Rules">
  <Description>
    Rules which verify the content and formatting of code documentation.
  </Description>
  <Properties>
    <BooleanProperty
      Name="IgnorePrivates"
      DefaultValue="False"
      FriendlyName="Ignore privates"
      Description="Do not require documentation for elements with private access."
    />
    <BooleanProperty
      Name="IgnoreInternals"
      DefaultValue="False"
      FriendlyName="Ignore internals"
      Description="Do not require documentation for elements with internal access."
    />
    <BooleanProperty
      Name="IncludeFields"
      DefaultValue="True"
      FriendlyName="Include fields"
      Description="Require documentation for fields."
    />
    <StringProperty
      Name="CompanyName"
      DefaultValue=""
      FriendlyName="Company name"
      Description="The company name to display in file headers."
    />
    <StringProperty
      Name="Copyright"
      DefaultValue=""
      FriendlyName="Copyright tag"
      Description="The copyright tag to display in file headers."
    />
  </Properties>
  <Rules>
    <RuleGroup Name="Element Documentation">
      <Rule Name="ElementsMustBeDocumented" CheckId="SA1600">
        <Context>The {0} must have a documentation header.</Context>
        <Description>Validates that an element contains a properly formatted documentation header.</Description>
      </Rule>
      <Rule Name="PartialElementsMustBeDocumented" CheckId="SA1601">
        <Context>The partial {0} element must have a documentation header containing either a summary tag or a content tag.</Context>
        <Description>Validates that a partial class, struct, etc. contains a valid documentation header which contains either a summary tag or a content tag.</Description>
      </Rule>
      <Rule Name="EnumerationItemsMustBeDocumented" CheckId="SA1602">
        <Context>The enumeration sub-item must have a documentation header.</Context>
        <Description>Validates that an item within an enumeration contains a properly formatted documentation header.</Description>
      </Rule>
      <Rule Name="DocumentationMustContainValidXml" CheckId="SA1603">
        <Context>The documentation header is composed of invalid Xml: {0}</Context>
        <Description>Indicates that a documentation header is composed of invalid Xml and cannot be parsed.</Description>
      </Rule>
      <Rule Name="ElementDocumentationMustHaveSummary" CheckId="SA1604">
        <Context>The documentation header must have a summary tag.</Context>
        <Description>Validates that a documentation header contains a properly formatted summary tag.</Description>
      </Rule>
      <Rule Name="PartialElementDocumentationMustHaveSummary" CheckId="SA1605">
        <Context>The partial element's documentation header must contain either a summary tag or content tag.</Context>
        <Description>Validates that a partial class, struct, etc. contains a documentation header with a properly formatted summary tag or content tag.</Description>
      </Rule>
      <Rule Name="ElementDocumentationMustHaveSummaryText" CheckId="SA1606">
        <Context>The summary section in the documentation header must not be empty.</Context>
        <Description>Validates that an element's summary tag contains a filled-in description.</Description>
      </Rule>
      <Rule Name="PartialElementDocumentationMustHaveSummaryText" CheckId="SA1607">
        <Context>The summary or content section in the documentation header must not be empty.</Context>
        <Description>Validates that a partial class, struct, etc. contains a documentation header with a filled-in summary description.</Description>
      </Rule>
      <Rule Name="ElementDocumentationMustNotHaveDefaultSummary" CheckId="SA1608">
        <Context>The documentation header still contains the default summary text generated by Visual Studio.</Context>
        <Description>Validates that the summary tag in an element's documentation header is not the default text generated by Visual Studio.</Description>
      </Rule>
      <Rule Name="PropertyDocumentationMustHaveValue" CheckId="SA1609" DisabledByDefault="true">
        <Context>The public or protected property's documentation header must contain a value tag.</Context>
        <Description>Validates that a public or protected property contains a documentation header with a value tag.</Description>
      </Rule>
      <Rule Name="PropertyDocumentationMustHaveValueText" CheckId="SA1610" DisabledByDefault="true">
        <Context>The value section in the property's documentation header must not be empty.</Context>
        <Description>Validates that a property's value tag contains a filled-in description.</Description>
      </Rule>
      <Rule Name="ElementParametersMustBeDocumented" CheckId="SA1611">
        <Context>The documentation header must contain param tags matching the element's parameter list.</Context>
        <Description>Validates that an element's documentation header contains a param tag for each item in the element's parameter list.</Description>
      </Rule>
      <Rule Name="ElementParameterDocumentationMustMatchElementParameters" CheckId="SA1612">
        <Context>The param tags in the documentation header must match the element's parameter list.</Context>
        <Description>Validates that an element's documentation header does not contain param tags for parameters which do not exist in the element's parameter list.</Description>
      </Rule>
      <Rule Name="ElementParameterDocumentationMustDeclareParameterName" CheckId="SA1613">
        <Context>All param tags in the documentation header must contain a 'name' attribute.</Context>
        <Description>Validates that all param tags in an element's documentation header contain a filled-in name attribute.</Description>
      </Rule>
      <Rule Name="ElementParameterDocumentationMustHaveText" CheckId="SA1614">
        <Context>The documentation text within the param tag for the '{0}' parameter must not be empty.</Context>
        <Description>Validates that an element's documentation header contains filled-in descriptions for each parameter in the element's parameter list.</Description>
      </Rule>
      <Rule Name="ElementReturnValueMustBeDocumented" CheckId="SA1615">
        <Context>The documentation header must contain a returns tag since the element has a return value.</Context>
        <Description>Validates that an element's documentation header contains a returns tag if the element has a return value.</Description>
      </Rule>
      <Rule Name="ElementReturnValueDocumentationMustHaveText" CheckId="SA1616">
        <Context>The returns section in the documentation header must not be empty.</Context>
        <Description>Validates that an element's returns tag contains a filled-in description.</Description>
      </Rule>
      <Rule Name="VoidReturnValueMustNotBeDocumented" CheckId="SA1617">
        <Context>The documentation header should not contain a returns tag, since the element has no return value.</Context>
        <Description>Validates that an element's documentation header does not contain a returns tag if the element has no return value.</Description>
      </Rule>
      <Rule Name="GenericTypeParametersMustBeDocumented" CheckId="SA1618">
        <Context>The documentation header must contain typeparam tags matching the generic types for the {0}.</Context>
        <Description>Validates that an element's documentation header contains a typeparam tag for each of the element's generic types.</Description>
      </Rule>
      <Rule Name="GenericTypeParametersMustBeDocumentedPartialClass" CheckId="SA1619">
        <Context>
          The documentation header must contain typeparam tags matching the generic types for the {0}. If the typeparam
          tags are documented on another part of the partial {0}, change the 'summary' tag to a 'content' tag to indicate that the
          primary documentation is placed on another part of the partial {0}.
        </Context>
        <Description>Validates that a partial class, struct, etc. contains a documentation header with a typeparam tag for each of the element's generic types, unless these types are documented on another part of the element.</Description>
      </Rule>
      <Rule Name="GenericTypeParameterDocumentationMustMatchTypeParameters" CheckId="SA1620">
        <Context>The typeparam tags in the documentation header must match the generic types for the {0}.</Context>
        <Description>Validates that an element's documentation header does not contain typeparam tags for types which are not part of the element's generic type list.</Description>
      </Rule>
      <Rule Name="GenericTypeParameterDocumentationMustDeclareParameterName" CheckId="SA1621">
        <Context>All typeparam tags in the documentation header must contain a 'name' attribute.</Context>
        <Description>Validates that all typeparam tags in an element's documentation header contain a filled-in name attribute.</Description>
      </Rule>
      <Rule Name="GenericTypeParameterDocumentationMustHaveText" CheckId="SA1622">
        <Context>The documentation text within the typeparam tag for the '{0}' parameter must not be empty.</Context>
        <Description>Validates that an element's documentation header contains filled-in descriptions for each item in the element's generic type list.</Description>
      </Rule>
      <Rule Name="PropertySummaryDocumentationMustMatchAccessors" CheckId="SA1623">
        <Context>The property's documentation summary text must begin with: {0}</Context>
        <Description>Validates that a property's summary description text begins with the correct syntax, depending upon whether the property exposes get or set accessors.</Description>
      </Rule>
      <Rule Name="PropertySummaryDocumentationMustOmitSetAccessorWithRestrictedAccess" CheckId="SA1624">
        <Context>Because the property only contains a visible get accessor, the documentation summary text must begin with '{0}'.</Context>
        <Description>Validates that a property's summary description text does not include a description for a set accessor when the property exposes only a get accessor.</Description>
      </Rule>
      <Rule Name="ElementDocumentationMustNotBeCopiedAndPasted" CheckId="SA1625">
        <Context>The documentation header contains two or more identical documentation strings. The only documentation text which may be duplicated is '{0}'.</Context>
        <Description>Validates that an element's documentation header does not contain repeated documentation text.</Description>
      </Rule>
      <Rule Name="SingleLineCommentsMustNotUseDocumentationStyleSlashes" CheckId="SA1626">
        <Context>Single-line comments must not begin with three slashes, which are reserved for lines within an Xml documentation header.</Context>
        <Description>Validates that comments do not begin with three forward slashes in a row, making them difficult to distinguish from documentation headers.</Description>
        <!--TODO: Move this to readability analyzer.-->
      </Rule>
      <Rule Name="DocumentationTextMustNotBeEmpty" CheckId="SA1627">
        <Context>The documentation text within the {0} tag must not be empty.</Context>
        <Description>Validates that the description within a documentation tag is filled-in.</Description>
      </Rule>
      <Rule Name="DocumentationTextMustBeginWithACapitalLetter" CheckId="SA1628" DisabledByDefault="true">
        <Context>The documentation text within the {0} tag must begin with a capital letter.</Context>
        <Description>Validates that the documentation text within a documentation section begins with a capital letter.</Description>
      </Rule>
      <Rule Name="DocumentationTextMustEndWithAPeriod" CheckId="SA1629" DisabledByDefault="true">
        <Context>The documentation text within the {0} tag must end with a period.</Context>
        <Description>Validates that the documentation text within a documentation section ends with a period.</Description>
      </Rule>
      <Rule Name="DocumentationTextMustContainWhitespace" CheckId="SA1630">
        <Context>The documentation text within the {0} tag does not contain any whitespace between words, indicating that it
          most likely does not follow a proper grammatical structure required for documentation text.</Context>
        <Description>Verifies that the documentation text within a documentation section contains at least two words, separated by whitespace.</Description>
      </Rule>
      <Rule Name="DocumentationMustMeetCharacterPercentage" CheckId="SA1631">
        <Context>The documentation text within the {0} tag does not appear to follow a proper grammatical structure required for documentation text.</Context>
        <Description>Verifies that the documentation text within a documentation section does not contain an excessive amount of symbols, making it difficult to read.</Description>
      </Rule>
      <Rule Name="DocumentationTextMustMeetMinimumCharacterLength" CheckId="SA1632" DisabledByDefault="true">
        <Context>The documentation text within the {0} tag must be at least {1} characters in length. Documentation
          failing to meet this guideline most likely does not follow a proper grammatical structure required for documentation text.</Context>
        <Description>Verifies that the documentation text within a documentation section meets or exceeds the minimum length.</Description>
      </Rule>
      <Rule Name="ConstructorSummaryDocumentationMustBeginWithStandardText" CheckId="SA1642">
        <Context>The documentation text within the constructor's summary tag must begin with the text: {0}.</Context>
        <Description>Verifies that a constructor's summary text begins with the appropriate wording.</Description>
      </Rule>
      <Rule Name="DestructorSummaryDocumentationMustBeginWithStandardText" CheckId="SA1643">
        <Context>The documentation text within the destructor's summary tag must begin with the text: {0}.</Context>
        <Description>Verifies that a destructor's summary text begins with the appropriate wording.</Description>
      </Rule>
      <Rule Name="DocumentationHeadersMustNotContainBlankLines" CheckId="SA1644">
        <Context>The documentation header must not contain blank lines. Use the 'para' tag to insert line breaks within documentation text.</Context>
        <Description>Verifies that a documentation header does not contain blank lines.</Description>
      </Rule>
      <!-- The follow rule cannot be disabled, because if this occurs then many other rules will not be run, with no further message shown to the user. -->
      <Rule Name="IncludedDocumentationFileDoesNotExist" CanDisable="false" CheckId="SA1645">
        <Context>The included documentation header file does not exist or cannot be loaded: {0}</Context>
        <Description>Verifies that an included documentation header file can be loaded.</Description>
      </Rule>
      <Rule Name="IncludedDocumentationXPathDoesNotExist" CheckId="SA1646">
        <Context>The XPath string '{0}' cannot be loaded from the included documentation file: {1}</Context>
        <Description>Verifies that an included documentation tag's XPath expression is valid.</Description>
      </Rule>
      <Rule Name="IncludeNodeDoesNotContainValidFileAndPath" CheckId="SA1647">
        <Context>The 'include' tag does not contain a valid 'file' and 'path' attribute: {0}</Context>
        <Description>Verifies that an 'include' tag contains a valid file and path attribute.</Description>
      </Rule>
      <Rule Name="InheritDocMustBeUsedWithInheritingClass" CheckId="SA1648">
        <Context>The 'inheritdoc' tag should not be used when the class or interface does not inherit from a base class or interface.</Context>
        <Description>Verifies that an 'inheritdoc' tag is not used when the class or interface does not inherit from a base class or interface.</Description>
      </Rule>
      <Rule Name="ElementDocumentationMustBeSpelledCorrectly" CheckId="SA1650">
        <Context>The documentation text within the {0} tag contains incorrectly spelled words: {1}</Context>
        <Description>Validates that an element's documentation header contains correctly spelled words.</Description>
      </Rule>
    </RuleGroup>
    <RuleGroup Name="File Headers">
      <Rule Name="FileMustHaveHeader" CheckId="SA1633">
        <Context>The file has no header, the header Xml is invalid, or the header is not located at the top of the file.</Context>
        <Description>Validates that a file contains a properly formatted file header.</Description>
      </Rule>
      <Rule Name="FileHeaderMustShowCopyright" CheckId="SA1634">
        <Context>The file header must contain a copyright tag.</Context>
        <Description>Validates that a file header contains a copyright tag.</Description>
      </Rule>
      <Rule Name="FileHeaderMustHaveCopyrightText" CheckId="SA1635">
        <Context>The copyright tag in the file header must not be empty.</Context>
        <Description>Validates that a file header contains a filled-in copyright tag.</Description>
      </Rule>
      <Rule Name="FileHeaderCopyrightTextMustMatch" CheckId="SA1636" CanDisable="false">
        <Context>The copyright tag in the file header must contain the following text: {0}</Context>
        <Description>Validates that a file header contains a copyright matching specific copyright text.</Description>
      </Rule>
      <Rule Name="FileHeaderMustContainFileName" CheckId="SA1637">
        <Context>The copyright tag in the file header must contain a 'file' attribute which contains the name of the file.</Context>
        <Description>Validates that a file header contains a file attribute.</Description>
      </Rule>
      <Rule Name="FileHeaderFileNameDocumentationMustMatchFileName" CheckId="SA1638">
        <Context>The file attribute in the file header's copyright tag must contain the name of the file.</Context>
        <Description>Validates that a file header contains a file attribute which contains the name of the file.</Description>
      </Rule>
      <Rule Name="FileHeaderMustHaveSummary" CheckId="SA1639" DisabledByDefault="true">
        <Context>The file header must contain a non-empty summary tag.</Context>
        <Description>Validates that a file header contains a filled-in summary description.</Description>
      </Rule>
      <Rule Name="FileHeaderMustHaveValidCompanyText" CheckId="SA1640">
        <Context>The copyright tag in the file header must contain a company attribute which contains the name of the company.</Context>
        <Description>Validates that a file header contains a filled-in company attribute.</Description>
      </Rule>
      <Rule Name="FileHeaderCompanyNameTextMustMatch" CheckId="SA1641" CanDisable="false">
        <Context>The company attribute in the file header must contain the following company name: {0}</Context>
        <Description>Validates that a file header contains a company attribute which contains a specific company name.</Description>
      </Rule>
      <Rule Name="FileHeaderFileNameDocumentationMustMatchTypeName" CheckId="SA1649">
            <Context>The file attribute in the file header's copyright tag must contain the name of the first type in the file and can be any of these: {0}</Context>
            <Description>Validates that a file header contains a file attribute which contains the name of the first type in the file.</Description>
        </Rule>
    </RuleGroup>
  </Rules>
</SourceAnalyzer>
